The Business Master (3rd Edition)

home *** CD-ROM | disk | FTP | other *** search

/ The Business Master (3rd Edition) / The Business Master (3rd Edition).iso / files / utilfile / puff / puff.doc < prev next >

Wrap

Text File | 1988-06-17 | 48.0 KB | 963 lines

******************************************************************** * Documentation for PUFF V3.05 - Dave Mitchell April 1988 * ******************************************************************** PUFF is a directory and file browser which pops up on demand. It takes up between 29 and 42K of memory when resident (depending on installation options). It runs under DOS 2 or 3 on any model PC and will work on both Mono and Color adapters. Once installed you pop it up at any time by pressing the hot-key which by default is Alt-D. This gives you the ability to browse directories and both ASCII and non-ASCII files within other programs such as word processors, spread- sheets, debuggers or even at the DOS prompt. It's intended to be very easy to use and contains several screens of on-line help accessible via the F1 key so you shouldn't need to read this document to use it! PUFF makes it possible to do things like: - browse the source of a program while debugging it - check the name of a file in a directory before loading it into a spread-sheet - quickly move up and down a directory tree looking for a file - check when you last saved a particular file - copy part or all of one file into an editor or word processor - see how much room there is on a diskette before saving a file - erase, copy or rename files at any time There are three reasons why PUFF may not be able to pop up when you want it to: - the application that's currently running is not asking for a keystroke. PUFF won't pop up in long-running "batch" programs like compiles or assemblies. - the current display is in a graphics mode. PUFF can only pop up in text modes. - at the time you ask PUFF to pop up, DOS is busy. PUFF checks to make sure that nothing dangerous (such as file I/O) is going on when you ask it to pop up. Despite all my efforts, PUFF is still not entirely "crash-proof". See the section on THINGS TO AVOID for more details. SUMMARY OF CHANGES PUFF Version 3 is a major rewrite of PUFF. Many new features have been added and a few have been dropped. Here's a summary: General Changes: - support for larger screens (43-line etc) - some support for enhanced keyboard (although PUFF doesn't know names such as F11, F12 etc, they can be set as the hot-key) - better bw80 support (treated as Mono not Color) - all PUFFSET customising functions now included - the directory/file buffer is now 6 or 12K - the PUFF box can be quickly moved to screen corners using Home, End PgUp and PgDn keys - when pasting, line feeds can be ignored or pasted - the normal cursor is suppressed when PUFF is popped up - PUFF now always pops up on the current DOS screen (can't force Mono anymore) - PUFF no longer supports 40-column screens In Directory Browse: - new popup menu of commands via "?" - attributes can be shown (instead of size) - date/time are properly country-dependent - sorting is almost twice as fast - original DOS order can be restored - new commands allow copy, erase and rename of files (and rename of directories and moving of files) - can now switch directly to another directory via 'N' command - customise options menus available directly via 'O' command A number of commands have had to change "name": D does Directory Refresh (was R for Refresh) since R is Rename T forces TEXT mode file browse (was A for ASCII) since A now toggles Attribute/size display In File Browse: - new popup menu of commands via "?" - can now switch directly to another file via 'N' command - customise options menus available directly via 'O' command - browsing is almost twice as fast - searching is almost twice as fast - search string can always be entered in hex or text - search can be case sensitive or not as required - in text mode, the cursor moves as in a normal editor A number of commands have had to change "name": T goes from HEX to Text mode (used to be A for ASCII) A switches to ASCII rather than EBCDIC when in HEX mode (was T for Translate) since T goes to Text mode R does repeat search (was N for Next) since N goes to New file INSTALLING PUFF When invoked, PUFF looks for its profile in the current and root directories of the current drive. The profile, a file called PUFF.PRO, can be created or tailored using PUFF itself (see the section "Customising PUFF"). Use SUBST, EXT, SRCHDIR or a similar program if you want to put it somewhere else. If PUFF can't find its profile it uses default values. The PUFF command looks like this: PUFF [hotkey] [initvu] [/n][/e][/s][/b][/l][/q][/x][/h] or PUFF ? The second form will give you a brief description of PUFF and the syntax of the first form. All the parameters in the first form of the command are optional. The first, the hot-key, is Alt-D by default but PUFF will accept: a-x where x is any letter a-z (26 Alt keys) c-x where x is any letter a-z (26 Ctrl-keys) fn where n is any number 1-10 (10 Function keys) a-fn where n is any number 1-10 (10 Alt-Function keys) c-fn where n is any number 1-10 (10 Ctrl-Function keys) s-fn where n is any number 1-10 (10 Shift-Function keys) The default hot-key can be changed by creating a new PUFF profile. See the section "CUSTOMISING PUFF" for details. Function keys F1 and F2 have special uses inside PUFF so they should not be used as hot-keys. The second parameter, initvu, lets you specify the name of a file which PUFF will display on first popping up (rather than displaying the main menu). Note PUFF will treat anything it doesn't recognize as a hot-key as an initvu specification. If your initvu option could be mistaken for a hot key (e.g. "F2") then you MUST specify the hot-key too. If the name matches a set of files (e.g. it contains an asterisk), then PUFF will popup in directory browse. The /r option lets you `remove' a copy of PUFF that is already resident. This can be useful in BAT files that invoke programs incompatible with PUFF, as a way of ensuring that PUFF is not present. If you attempt to install PUFF when it already resident PUFF will not re-install itself but will tell you what the hot-key of the already installed version is. The /n (Normal) option restricts PUFF to the top 25 lines of the screen. This reduces memory requirements by about 4K. The /e (EGA) option allows PUFF to use up to 50 screen lines (on an EGA, VGA or MCGA), but increases memory requirements by about 4K. The /s (Small) option forces PUFF to use only 6K of buffer space, reducing its memory requirements at the cost of performance. The /b (Big) option makes PUFF use 12K of buffer space, by doubling the sizes of PUFF's directory and file buffers. This allows PUFF to handle directories with up to 555 files. If there are less than 275 files then PUFF does not have to re-read the directory when returning from a file browse, improving performance considerably. The extra file buffer makes scrolling through a file faster too, since the file is read in 4k rather than 2k chunks. The /l (Loud) option makes PUFF install itself `noisily', producing a banner which gives its version number and buffer sizes. The /q (Quiet) option makes PUFF install itself `quietly', without any banner or messages. The /x (eXclude) option excludes the installation of on-line help. This makes PUFF take up less storage (about 3K less at present but this might increase if more help is added) but means that inside PUFF only a single screen of help is available. The /h option (Help) includes the on-line help. PUFF.COM is about 23K in size but takes up 29-42K when installed. PUFF'S MAIN MENU When you press the hot-key PUFF will test to see if it's safe to pop up. It won't pop up if DOS is doing something that it would be dangerous to interrupt. If you try to pop up when the screen is in a graphics mode, PUFF will beep instead (earlier versions looked for a Mon screen in this case). When popped up, the main PUFF menu offers the following options: .Browse Current Directory .Select Directory for Browsing .Customise (set options) .Write new profile (save options) .Quit (pop-down) .Remove PUFF from Memory The current directory is shown at the bottom of the menu. One of the options will be high-lighted. The cursor up and down keys move this bar and the Enter or Cursor Right keys select the high-lighted option. You can also select an option by typing the first letter on the line (B for Browse, R for Remove and so on). F1 will usually give context-sensitive help (unless the /x option has been used). PUFF treats the Esc key as a general "cancel" or "quit" key. PUFF will also let you `exit immediately' by pressing the hot-key rather than Esc. You can do this at any time (except when help is being displayed or input being requested). If you leave PUFF this way you will return to where you left off when you pop up PUFF again. Most of the time PUFF responds to the F2 key by copying the active screen to the alternate display - if you've got one! This allows you to save the PUFF screen on the other display and then consult the data it contains when you return to the original application. Note that the attributes are `not' copied since some color attributes can cause unpleasant blinking on a Mono display. BROWSE CURRENT DIRECTORY This option will cause PUFF to display the current directory. On entry to PUFF this will be the current directory on the current drive (unless PUFF has been customised - see "CUSTOMISING PUFF" below). Twelve lines are shown, with the current line at the centre. Each line shows the filename, size and date/time stamp. Sub-directories are indicated by <DIR>. Instead of filesize, PUFF can display the file attributes. The order in which the files are initially displayed is by default the same order as a DOS DIR command would display, but you can make it by name, extension, date or size by forcing PUFF to do a sort before it displays the list. See the section on "CUSTOMISING PUFF" for details. PUFF displays file dates in either MM/DD/YY (US) format, DD/MM/YY (European) format or in YY/MM/DD format (Japanese etc). and times in 12- or 24-hour clock style, depending on the COUNTRY code setting in CONFIG.SYS, just as the DOS DIR command does. In directory browse PUFF responds to keys as follows: ? pops up a command menu A (Attribute) toggle between display of attributes or file size C (Copy) copies current file D (Display) refresh directory buffer (eg after erase/rename/copy) E (Erase) erases current file F (Free) display free space available on drive H (HEX) as Right, but forces display to HEX mode M (Move) moves current file N (New) allow switch to new directory directly O (Options) access the options menus P (Paste) paste a file name or its contents into the current application Q (Quit) quit (return to Main Menu) R (Rename) renames current file S (Sort) sort current directory by Name, Extension, Size, Date or back to DOS order T (Text) as Right, but forces display to text mode Up move up 1 line (towards start of directory) Down move down 1 line PgUp move up 11 lines PgDn move down 11 lines Ctrl-Home move to first entry Ctrl-End move to last entry Left browse parent directory (if any) Right browse selected sub-directory or file Enter same as Right + switch to next drive (eg from A: to B:) - switch to previous drive (eg from B: to A:) Esc return to Main Menu F1 give help about directory browse mode F2 copy active screen to other display Some of these commands demand a bit more explanation. THE ? COMMAND Because it's easy to forget just what letter keys PUFF responds to, the new "?" command pops up a command menu. You can then select a command by moving the hilighting bar, or by typing its first letter. The cursor Up, Down, PgUp, PgDn, Home and End keys all move the bar. The bottom line of the menu shows an up and/or down arrow if more unseen options lie above the first line or below the last line seen. As well as selecting an item, you can pop-down the menu by pressing Esc. COPY, ERASE, MOVE and RENAME Erase will ask you if you are sure before doing the erase and all four commands can be cancelled by pressing Esc. If you erase, move or rename files, PUFF leaves the entries in the display, but replaces the filesize field with the word <ERASED>, <MOVED> or <RENAMED>. When marked like this a file or directory cannot be browsed, renamed or copied. The 'D' command will properly refresh the display. Note that you can `move' files to another directory and rename `directories' as well as files (you can't erase or move directories though, and PUFF does not support RemoveDir). When copying, moving or renaming be careful. If the new name does not begin with a drive specifier or backslash PUFF will prefix the name you give with the current PUFF directory (which may not be the same as the current DOS directory). When moving or renaming the new name may just be a drive letter followed by a colon or a path ending with a backslash. In these cases, PUFF will use the old filename.extension for the target file. THE DISPLAY COMMAND The Display command causes PUFF to re-read the directory. This is useful when you have changed diskettes while PUFF is popped up, or if you have popped down using the hot-key and then created, modified or erased some files so that when you pop up again the directory will not be up to date. Pressing D will cause the directory to be re-read. THE FREE COMMAND The free space display, which was automatic in earlier versions of PUFF, is now produced using the F command. This change was made because computing free space can take quite a while, particularly on a fixed disk with a lot of directories and files. THE NEW COMMAND This option lets you switch to another directory directly rather than having to use the cursor left and right keys to traverse the directory tree. THE OPTIONS COMMAND This lets you access the two customizing menus from within directory browsing. This makes it quicker to move the PUFF box around, change the hot-key or screen colours since PUFF no longer has to re-read the directory when you go back. THE PASTE COMMAND The Paste command causes PUFF to pop-down and then "paste" key- strokes into the application program that was running when PUFF was popped up. You can paste the name (i.e. filename.ext), the full name (i.e. drive:\path\filename.ext) or the contents of the file (see the section on the "PUFF FILE BROWSER" for how to paste just part of the contents of a file). The keystrokes will appear where the cursor was, just as if you had typed them in. When you pop PUFF up again you will go back to the directory display, as though you had popped down using the hot-key. Pasting the contents of a file can be used as a sort of BAT or input redirection facility or to copy one file into another in an editor that does not support paths. In general PUFF treats each byte in the file as a separate keystroke. It stops at Ctrl-Z and treats a X'00' byte as a signal that the following byte is an Extended ASCII code. Thus the sequence X'003B' would cause PUFF to send back the code for function key F1 (whose scan code is 59 = X'3B'). For a list of the codes associated with the cursor keys, Alt-keys and various function/shift combinations see the BASIC Manual (Appendix D) or the Technical Reference Manual. Some editors treat a carriage return as a signal to go to the start of the current line and require a different key to be pressed to `insert' a blank line. PUFF can be made, through its profile, to return some other keystroke instead of the carriage return (X'0D') to force a new line to be inserted and can filter out Line Feeds if needed. Thus you can make PUFF treat a carriage return as an F9 (which inserts a line in PE) or F2 (which does the same in KEDIT). For more details, see the section on `CUSTOMIZING PUFF'. Note that to paste into most editors you must also make sure the cursor is in the data area rather than on the command line (unless the keystroke file includes something like an Esc to switch the cursor over). During pasting PUFF responds to the following keys: space bar - pause until another key is pressed + - speed up pasting - - slow down pasting any other key - terminate pasting and return to normal keyboard input THE SORT COMMAND Sorting is done in alphabetical order for Name, and in reverse order for Size (big files first) and Date (newest files first). Sorting by extension actually sorts by name within extension. The current sort order is displayed on the `Browsing Directory' line. Note that PUFF now lets you go back to the original DOS order after sorting if you want. OTHER COMMANDS The Left and Right keys also deserve a bit more explanation. If PUFF was popped up when the current DOS directory is C:\TOOLS then this is the directory that PUFF will display. Pressing the Left cursor key will cause PUFF to display the root directory while pressing Right or Enter when the current high-lighted line is a subdirectory called EDITORS will cause PUFF to display the C:\TOOLS\EDITORS directory. If the current line is a file then PUFF will display that (see "PUFF FILE BROWSER" later). PUFF tries to be intelligent about these keys. If you move right and then left again, you should get back to the line you came from in the higher directory (eg the EDITORS line) even if the directory has been sorted or files have been copied, erased or moved. If you start in a sub-directory and move left then PUFF should be bright enough to find the right line. The + and - keys also try to be intelligent. On a single floppy system, such as an XT, the A and B logical drives are mapped onto a single physical drive. Any reference to B when the current drive is A will cause DOS to display a message "Insert diskette for drive B". PUFF tries to avoid this by skipping over the logical drive which is not current. Thus + will skip from A to C and - from C to A if the current drive is A. If the current drive is B then - will not try to skip to A. One final point. PUFF has only a small 6K buffer (12K with /B option) so it can only store up to about 275 (or 555) directory entries. If the directory has more entries only the first 275 (or 555) will be shown. PUFF will display a message if there are too many files to display all of them. This message will only appear the first time you browse a given directory, but the 275 (or 555) will always be followed by a "+" if there are more files. You can use the "Select Directory for Browsing" option to select a subset of files from a large directory. PUFF FILE BROWSER From directory browsing you can select a file for viewing by pressing Cursor Right, Enter, T or H. For PUFF a text file is one which has a Carriage Return/Line Feed at the end of each record and a Ctrl-Z at the end of the file. The file browser operates in one of two modes: Text in this mode each line on the screen shows a file line. Long lines are truncated but PUFF allows sideways scrolling so that long lines can be viewed. The screen tells you which file line and column the cursor is at. This is the default mode for text files and is forced if you use the T command. HEX in this mode the screen is divided up into three vertical parts. On the left is the offset from the start of the file (in Hex), in the middle are 8 bytes of data in Hex while on the right are the same 8 bytes in ASCII (or in EBCDIC if EBCDIC translation is turned on). In Zoom mode there are 16 bytes of data on each line. This is the default mode for non-text files and is forced if you use the H command. If you enter the file browser using Enter or Cursor Right, PUFF guesses what sort of file is being browsed using an extremely simple algorithm. If the last byte of the file is Ctrl-Z or Line Feed it assumes the file is text and goes into text mode, if not it uses HEX mode. Alternatively you can force the mode by using T or H. TEXT MODE COMMANDS The following commands are available in ASCII mode: ? pops up a command menu E (Expand) expand/compress tab characters (tabs at every 8th column) G (Goto) go to line n H (Hex) switch to HEX mode N (New) allow switch to new file directly O (Options) access the options menus P (Paste) paste file contents Q (Quit) quit (return to directory browser) R (Repeat) repeat search for string S (Search) search for a text string Z (Zoom) switch to Zoom mode or back ' search for a hex string / search for a text string Up move cursor up 1 line (towards start of the file) Down move cursor down 1 line PgUp move up a screenful PgDn move down a screenful Ctrl-PgUp move up 100 lines Ctrl-PgDn move down 100 lines Ctrl-Home move to first line Ctrl-End move to last line Left move cursor left 1 column Right move cursor right 1 column Tab move cursor right 10 columns BackTab move cursor left 10 columns Ctrl-Right move cursor right a screen width Ctrl-Left move cursor left a screen width Home move cursor to column 1 End move cursor to end of line Esc return to directory browsing F1 give help about ASCII file browse mode F2 copy active screen to other display As with the directory browser, the new ? command pops up a command menu. One new feature of text mode is that the current position is shown by a normal blinking cursor which is moved by the cursor keys (just as in most editors). Earlier versions of PUFF always made the current position the top left of the window, which made searching and scrolling unfriendly to say the least! HEX MODE COMMANDS The following commands are available in HEX mode: ? pops up a command menu A (ASCII) switch to ASCII E (EBCDIC) switch to EBCDIC N (New) allow switch to new file directly O (Options) access the options menus P (Paste) paste file contents Q (Quit) quit (return to directory browser) R (Repeat) repeat search for string S (Search) search for a HEX string L (Low) toggle Low Hex display on and off T (Text) switch to text mode Z (Zoom) switch to Zoom mode or back ' search for a hex string / search for a text string Up move up 8/16 bytes (towards start of the file) Down move down 8/16 bytes PgUp move up a screenful PgDn move down a screenful Ctrl-PgUp move up 1024 bytes Ctrl-PgDn move down 1024 bytes Ctrl-Home move to first byte Ctrl-End move to end of file Left move up 1 byte Right move down 1 byte Esc return to directory browsing F1 give help about HEX file browse mode F2 copy active screen to other display As with the directory browser, the new ? command pops up a command menu. Note that PUFF tries to keep a count of the current file line in all modes. So if you switch from ASCII into HEX mode, scroll about and then return to text mode the line number should be correct. However if you jump directly to the end of the file (using Ctrl-End) PUFF will not know the line number unless you have previously scrolled there. In such a case the line number will show as ????. The current version of PUFF can be confused by attempting to display non-ASCII files in ASCII mode, particularly if the resulting lines appear to be more than 255 bytes long. The maximum size file you can browse is about 100 Megabytes! The Low Hex translate option lets you suppress the display of characters with ASCII codes below X'20'. These characters cause problems if you try to print the screen since they are treated by printers as control characters (form feed, line feed etc). EBCDIC translate lets you view a file, in the right-hand column, in EBCDIC form. Thus X'F1F2F3' will appear as the string '123'. This option can be useful when viewing Displaywrite files which are stored in EBCDIC form. PUFF displays the state of the toggle on the "Browsing HEX file" line. PASTING WITHIN FILE BROWSE When browsing a file you can make PUFF paste the file contents using the 'P' command. PUFF will then ask if you want to paste just the current line, the rest of the file or to go back to the start and paste the whole file. Note that in the first two cases pasting starts at the cursor position (rather than the beginning of the current line). SEARCHING IN PUFF The Search command lets you search for an ASCII or HEX string. The 'S' command expects a text string in text mode and a hex string (pairs of hex digits optionally separated by blanks) in hex mode. The / expects a text string (and can be useful in HE mode) while the ' command expects hex digits (and can be useful in text mode). The search starts at the current position in the file and you can terminate the search at any time by pressing any key. See the section Data Entry in PUFF for details of how the search string may be edited. Depending on the option setting searching can be case-insensitive or not. In the former case a search for "The" will stop at "the" or "THE" as well. Accented characters above X'7F' are also treated in this way, using the standard DOS rules for equivalence (so the upper and lower case c cedilla - x'80' and x'87' are treated as equivalent). The Repeat command will find the next occurrence of the string. In text mode, it starts on the current line, at the byte after the current column. In HEX mode, it starts at the byte after the current position which is essentially the same. Note that you can enter a search string in one mode (eg text) and then use Repeat in the other mode and PUFF will still search for the same string. ZOOM MODE The Z command switches between the normal PUFF browser and full- screen mode. In full-screen mode PUFF responds to the same set of commands but obviously displays more of the file at once - 25 or more lines of 80 columns. In ZOOM mode, the PgUp and PgDn keys are adjusted so that they still scroll a pageful (i.e. for PgDn what was the bottom line becomes the top). The Ctrl-Left and Ctrl-Right keys in text mode are similarly adjusted. SELECT DIRECTORY FOR BROWSING This lets you select any directory for browsing. PUFF will accept most combinations of drive, path and filespec information, so the following are all valid: C:\ all files in root directory on C C: all files in current directory on C C:\*.COM all COM files in root directory on C C:\TOOLS\ all files in TOOLS subdirectory on C C:\TOOLS ditto TOOLS\ displays all files in TOOLS subdirectory of current directory on current drive. TOOLS ditto TO*.* all files/sub-directories beginning with TO in current directory on current drive If the selected drive/directory has no files PUFF will beep and display a message. Entering a blank line will cause the current directory to be reset to the value it had on entry to PUFF. You can cancel this option by pressing Esc. See the section "DATA ENTRY IN PUFF" for details of how a filespec may be edited. CUSTOMIZE (SET OPTIONS) The choices on this menu are described in detail in the section "CUSTOMIZING PUFF". WRITE A NEW PROFILE (SAVE OPTIONS) This causes PUFF to write a new profile, using the current value of all options. Thus once you have set these to the values you like and created a new profile, the next time you install PUFF the options will all get the appropriate values. QUIT This option causes PUFF to pop down out of sight. The same effect is produced by pressing Esc. REMOVE PUFF FROM MEMORY This will work only if PUFF was the last DOS extension you installed that takes over INT 16H, the Keyboard interrupt (other programs that do this include GWNOTE, PCCALC, PSRD, KQE and the BelleSoft Pop-Ups). You can cancel this option by pressing Esc. CUSTOMISING PUFF The customising facilities are available from the main menu (via 'C' for Customise) or from directory of file browsing (via 'O' for Options). The customise menu offers the following choices: Set initial view options (a submenu) Move PUFF Menu Change Pop-Up key Beep Tone/Duration Normal screen colour Emphasised screen colour Paste Enter key Ignore linefeeds Date/time of copyfile Quit SET INITIAL VIEW OPTIONS This sub-menu is described offers the following choices: Set initial drive/directory Expand Tabs Zoom to full screen Directory Order LoHex characters Hex display encoding Attribute or Size Case Sensitive search Quit Most of these settings determine the values of the appropriate variables when a new directory or file is entered, though all can altered while file browsing using the appropriate commands. The first option is different however. It corresponds to the "InitVu" option on the PUFF command, and determines which drive, directory or file PUFF displays when popped up. A setting of "Current" makes PUFF pop up at the main menu, using the current DOS directory on the current DOS drive as a starting point. Entering a drive letter and/or a directory here will cause PUFF to use that drive/directory as a starting point instead and PUFF will initially pop up in directory browsing (rather than the main menu). If the name resolves to a file (rather than a directory) then PUFF will initially pop up in file browsing. The defaults for these options are: .the current DOS drive and directory are used .tabs are initially expanded in text mode. .zoom mode is used. .the initial order in which a directory is displayed is the order given by a DOS dir command .hex characters below X'20' (which because they are used for printer control can disrupt a Print Screen operation) are displayed "as-is" rather than as ".". .HEX file encoding defaults to ASCII. .file sizes rather than atttributes are displayed. .searching is not case-sensitive. MOVE PUFF MENU This option lets you move the pop-up PUFF menu around the screen using the left, right, up and down keys or to one of the four screen corners using the Home, PgUp, End or PgDn keys. You can fix it in a new position by pressing Enter. You can cancel this option by pressing Esc. CHANGE POP-UP KEY This lets you change the pop-up key by pressing the new one. The new key can be any key with an Extended ASCII code associated with it (i.e. it includes combinations like Alt-1 and Ctrl-PgUp). Be careful though, it's not very sensible to make it F1 or F2 or one of the cursor keys. PUFF will not let you choose ENTER as a pop-up key. You can cancel this option by pressing Esc. PUFF tries to display the name of the selected key, but the names it knows are limited to the 92 keys listed above in the section "INSTALLING PUFF". Any other key will be displayed as "Unknown". BEEP TONE/DURATION The cursor keys are used to change the nature of PUFF's beep. Note that here the Esc key is used to reset things to the defaults, the only exit from this option is via Enter (which fixes the values). SCREEN COLOR The cursor keys are used to change the screen attributes. 'Normal' means the default PUFF color, 'Emphasised' is what PUFF uses to indicate a selected option or hilight an error message. Here again the Esc key is used to reset things to the defaults, the only exit from this option is via Enter (which fixes the values). PASTE ENTER KEY AND IGNORE LINEFEEDS The first of these determines how Carriage Returns are to be treated during pasting. PUFF lets you replace them with some other key. This is particularly useful when pasting into an editor that requires some special key to be pressed to insert a new line into the file. By default they are left as Carriage Returns. PUFF tries to display the name of the selected key, but the names it knows are limited to the 92 keys which can be assigned to the hot-key and the Enter key. Any other key will be displayed as "Unknown". If the Enter key (or whatever it's been replaced by) does the necessary "insert new line" fucntion, linefeeds should be ignored. However, in some editors both Enter and Linefeeds should be pasted. The first creates a new line (but may move the cursor to align with the first non-blank on the line above) and the second moves the cursor back to the start of the line. DATE/TIME OF COPYFILE When copying a file, PUFF let's you choose whether the date/time stamp on the new file should be the same as the old file (this is what the DOS COPY command does) or the current date and time. DATA ENTRY IN PUFF PUFF allows editing of data input rather like DOSEDIT. This facility is available when you use the "Select Directory for Browsing" option or the "SEARCH" command in the file browser. A small buffer of previously entered strings is maintained and during data entry PUFF responds to the following keys: Up retrieve previous stored string Down retrieve next stored string Home move cursor to start of string End move cursor to end of string Left move cursor one column to the left Right move cursor one column to the right Ins toggle insert mode (cursor shape changes) Del delete character at the cursor Backspace delete character before the cursor Enter pass current string to PUFF Esc cancel data entry The "ring" of stored strings is limited to 256 bytes. The normal cursor is a blinking underscore. In insert mode it's a blinking solid rectangle. SOME DESIGN DETAILS One of my main aims in writing PUFF was to fit it into a small amount of memory (originally 20-24K). This has significantly affected the design in a number of places. The purpose of this section is to outline some of the key aspects of PUFF's design, so that the interested user can understand why it does (or doesn't do) certain things in a particular way. USE OF STORAGE The PUFF.COM file, which is about 23K in size, is made up of: .Resident Code - this occupies about 12K. .Resident Data - this occupies about 5K and includes messages, menus, tables etc. .Initialization Code - this code, about 2K in size, is overwritten by PUFF's buffers when PUFF is resident. .Initialization Data - these messages and tables occupy about 1K and are overwritten by PUFF's buffers. .Help screens - these occupy about 3K and are overwritten by PUFF's buffers if the /X option is used. When resident, PUFF needs space for: .Screen Buffer - this is 4K in size. Before PUFF pops up it stores the existing screen in this buffer (2K of data and 2K of attributes). If the /E option is used the buffer is enlarged to 8K to allow 43 or even 50-line screens to be used. .Directory/File Buffer - without the /b option, this is 6K in size. The first 2K is reserved for directory use, so there is no need to re-read the directory when leaving file browse if the directory has less than 93 entries. In Directory Browse, PUFF uses 22 bytes for each entry, so the buffer will hold about 275 entries. Any sorting is done in place. In File Browse 4K of this is split into two 2K buffers. This is to avoid the excessive file I/O that would occur with a single buffer when scrolling back and forth near a buffer boundary. If the /b option is used the buffer is doubled to 12K, with room for 555 entries. The first 4K is reserved for directory use, so there is no need to re-read the directory when leaving file browse if the directory has less than 186 entries. The file browser uses the last 8k as two 4K buffers which halves the number of file I/O operations and thus improving scrolling speed. .Data Buffers - these are used to store the current file and directory names, to hold the search string during searches, and to build lines to be displayed on the screen. They occupy about 2K. Thus the total resident size is made up of: 12K resident code 5K resident data 3K help screens 10K-20K screen and file buffers 2K data buffers PERFORMANCE Because of its limited buffer space, certain operations take some time. For example, PUFF may have to rebuild and re-sort the directory whenever you leave the file browser, or go up from a sub-directory to its parent. Similarly, when scrolling or searching through a file, PUFF has to read each 2K or 4K chunk in turn, which takes some time. SCREEN I/O The low level video driver routines in PUFF, give particularly good performance on the Color Graphics Adapter. The routine used to move the PUFF menu about the screen is rather primitive, and looks very unsightly on a Color Display. However it is very small and since the menu is not moved very often it does not seem worth the space to improve it. TEXT FILE HANDLING PUFF can be confused if attempts are made to display, in text mode, files which do not conform to its expectations: .a CR/LF sequence at the end of each record .a Ctrl-Z at the end of the file (and nowhere else) .a maximum record length of 255 characters PUFF counts lines by looking for CR/LF sequences, and the line counter will be wrong if some other line terminator is used. Similarly PUFF displays the End of File message when it detects a Ctrl-Z, so files with embedded Ctrl-Z's will confuse it. DETERMINING RESIDENCY PUFF tests to see if it is already resident by following the storage allocation chain. This points it to each PSP in memory and it checks the code after each PSP to see if it is a copy of itself. The logic to do this is based on undocumented pointers in the Memory Control Blocks and PSPs, but seems reliable in DOS 2 and DOS 3. At worst another copy will be loaded when it should not be. Trapping INT 16 (Keyboard Request) PUFF takes over INT 16 and intercepts all application requests for keystrokes. The way this is done should be totally transparent except that in text modes, no application program will ever see PUFF's hot-key (since this will cause PUFF to pop up, or if already popped up, to pop down again). Note that in general PUFF can co-exist peacefully with other applications which intercept INT 16. Trapping INT 28 (DOS Idle Interrupt) PUFF intercepts INT 28 so that it can avoid popping up when DOS is usy. This is based on techniques described in PC Magazine for April 14th 1987 (Instant Acccess to Directories by Jeff Prosise - pages 313-334). PUFF should be able to co-exist peacefully with other popups. Prior to Version 2.3, PUFF hooked the INT 21H vector and was DOS version-dependent. The new technique should be much safer. ERROR MESSAGES The following is a list, in alphabetical order, of the messages that PUFF displays: - Can't go any deeper - press any key. - This message appears if you try to go deeper than eight levels into the directory tree. In fact, due to the limited width of PUFF's window you may not be able to see the full directory name before you get this deep (though PUFF does in fact maintain it internally). - Error copying file - press any key. - This message is displayed if PUFF detects an error when trying to copy a file. Possible reasons include a write-protected disk or an attempt to copy a file to a non-existent directory. - Error erasing file - press any key. - This message is displayed if PUFF detects an error when trying to erase a file. Possible reasons include a write-protected disk or an attempt to erase a read-only file or a directory. - Error in Hex string - Press any key. This message is displayed if a HEX search string contains an odd number of digits or a character other than a valid hex digit or blank. - Error reading file - Press any key. This message is displayed if PUFF detects an error when reading a file. - Error renaming file - press any key. This message is displayed if PUFF detects an error when trying to rename a file. Possible reasons include a write-protected disk or an attempt to move a file to a non-existent directory. - Error writing Profile - Some sort of error occurred while PUFF was trying to create PUFF.PRO, such as a write-protected diskette. - File is empty - press any key. - This message is displayed if you try to browse or paste a zero-length file. - No file(s) found - press any key. - This message is displayed if you try to browse an empty disk or directory or switch to browing a non-existent file - No search to repeat - press any key. - This message is displayed if the Repeat command is issued without there being a preceding search. - Not a file - press any key. - This message is displayed if you try to paste the contents of a directory. - Search interrupted - press any key. - This message is displayed if searching is terminated by the user pressing a key. - String not found - press any key. - This message is displayed if a search is unsuccessful. - Too many files - press any key. - This message is displayed if there are more files in the selected directory than PUFF's buffer can hold (275 or 555 if the /b option is used). - Unsafe to remove PUFF - This message is displayed if an attempt is made to remove PUFF when another resident program has taken over INT 16 or INT 28 since PUFF was installed. The following messages can appear during PUFF initialisation: - Bad or missing PUFF profile - Either the PUFF.PRO file could not be found in the current or root directories or it did not contain the necessary fields (in particular the string PUFF3 at the start). If no PUFF.PRO can be found, PUFF uses default values. - Invalid option - the PUFF command was followed by a / which was not followed by a valid option (B, E, H, L, N, Q, R, S and X are the valid options). - No resident version to remove - PUFF was invoked with the /R option and no resident version could be found. - PUFF does not support this version of DOS - PUFF will not run under DOS 1. PUFF should now run under all later versions of DOS, including the OS/2 Compatability Box. - PUFF is already installed - An attempt was made to install PUFF when PUFF was already resident. - Resident version cannot be removed - PUFF was invoked with the /R option but another DOS extension prevented the resident version from being removed. - Resident version removed - PUFF was invoked with the /R option and a resident version has been successfully removed - Warning - PUFF profile needs updating - PUFF was run with an out of date profile, so some new options will be set to their default values. Writing out the profile will allow these new options to be set as you would like. FORMAT OF PUFF.PRO The profile is a small file, 107 bytes long, containing the following fields: Content Offset Length Default Value (in Hex) marker 0 5 5055464633 ('PUFF3') hot-key scancode 5 2 0020 (Alt-D) normal mono attrib 7 1 20 (normal) hilite mono " 8 1 70 (reverse video) normal color " 9 1 1e (yellow on blue) hilite color " a 1 78 (black on grey) beep tone b 2 4B beep duration d 2 4B top box line f 1 1 left col (80 cols) 10 1 28 (decimal 40) quiet install 11 1 0 ()= No, 1= Yes) ega allowed 12 1 0 (0= No, 1= Yes) help included 13 1 0 (0= Yes,1= No) buffer size 14 1 0 (0= 6K, 1=12K) zoom files? 15 1 1 (1=no, 0= yes) expand tabs? 16 1 0 (0= no, 1= yes) directory order 17 1 0 (0=DIR, 1=size, 2=date (3=name, 4=extension) ASCII/EBCDIC 18 1 0 (0= ASCII, 1= EBCDIC) low hex switch 19 1 0 (0= display, 1= suppress) attr/size 1a 1 0 (0= size, 1= attributes) case sensitivity 1b 1 0 (0= insensitive, 1= sensitive) paste CR key 1c 2 0D1C (Carriage Return) linefeed 1e 1 0 (0= ignore, 1=paste) initial view 1f 72 0 (0 = use current) (else drive/path/filespec) Date format 68 1 0 (-1 means ask DOS, 0 = mmddyy) (1 = ddmmyy, 2 = yymmdd) Time format 69 1 0 (-1 means ask DOS, 0= 12h, 1= 24hr) Date/Time of copy 6a 1 0 (0= current time, 1= original time) Note that this profile is incompatible with that used by earlier versions of PUFF. The profile is loaded into PUFF.COM at offset 3 from the start of the program, overlaying the default values contained there. THINGS TO AVOID The architecture of PC/DOS does not allow programs like PUFF to be legal, decent and honest. There is no official way in which a resident program can get control, even at the DOS prompt, and issue DOS calls. In writing PUFF I've had to make use of a number of dirty tricks and to use undocumented interfaces. Even so PUFF is safe most of the time. Here are a few things which can cause problems: Displaying COM files and other arbitrary files in ASCII mode (the main symptom will be peculiar behaviour of PUFF's line counting) Pasting keystrokes from a non-ASCII file (anything could happen here since PUFF will return absurd and impossible values as keystrokes). Popping up PUFF when DOS has issued a critical error message (e.g. Abort, Retry or Ignore ).